home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _editors / editors / _zap / !Zap / Docs / E-Menu < prev    next >
Text File  |  1994-07-26  |  6KB  |  127 lines
  1. *************************************************************************
  2. * >E-Menu    Documents Zaps internal menu format            *
  3. *************************************************************************
  4.  
  5. If you are writing your own mode then you may add your own menu to appear off
  6. the the mode menu. See the C mode for an example.
  7.  
  8. You are asked to give an offset to a 'Zap menu structure' at offset e_menu in
  9. the mode table. This file documents the format of this structure.
  10. Alternatively you may wish to use the e_init entry point to set up your own
  11. menu from a menus file. The structure pointed to by e_menu is of the form:
  12.  
  13.     #&00    Menu name (12) (zero terminated)
  14.     #&0C    Menu width (os coords)
  15.     #&10    Module offset of 'update menu code' (0 if none)
  16.     #&14    Menu entries (x n)
  17.         -1 to terminate list of entries
  18.         
  19. Each menu entry is of the form:
  20.  
  21.     #&00    Flags:    b0-b7    Menu flags as for wimp. ie,
  22.             b0    Display tick to left of item
  23.             b1    Dotted line follows
  24.             b2    item writable
  25.             b3    generate submenu warning message (see below)
  26.             b4-b6    reserved
  27.             b7    ignored
  28.             b8-b15    Minimum buffer size to reserve for this menu
  29.                 entry (eg writable icon).
  30.             b16-b23    Internal use : save menu start in a memory
  31.             b24-b31    Icon colours / 0 for default
  32.     #&04    Submenu pointer:
  33.         If the submenu warning bit is clear then:
  34.             0=none
  35.             1-15=internal use : get from memory 1-15
  36.             >16 =offset in module of submenu (same structure).
  37.         If the submenu warning bit is set then this gives the module
  38.         offset of the code to be called to open the submenu (see
  39.         below).
  40.     #&08    Index word. This is a 'handle' for this menu entry which is
  41.         passed to the interpret code so the same interpret code
  42.         can be used for several menu entries. Contrary to the
  43.         documentation in previous versions this handle is treated
  44.         as a module offset (if non 0) and updated to an address
  45.         before being passed to your interpret code.
  46.     #&0C    Module offset of the interpret code to call when menu 
  47.         clicked on. (0 if none)
  48.     #&10    Text for this entry (0 terminated string of any length)
  49.     ALIGN before next entry.
  50.     
  51. This structure is relocatable and thus can be stored directly in your mode
  52. extension module. When Zap is run, it converts it into a standard wimp menu
  53. with all menu entries being indirected strings. The size of the indirected
  54. string buffer is set to that of the text for the entry unless offset #4
  55. specifies a greater amount. The other values are stored at negative offsets
  56. from the standard wimp structure:
  57.  
  58.     menu pointer
  59.     #-8    = Counter giving time menu last updated.
  60.     #-4    = Address of routine to handle updating of menu ticks etc:
  61.           If 0 then the standard routine is used which searches for
  62.            and commands on the menu and updates the ticks.
  63.           If >0 then it points to user specific code (see below)
  64.     
  65.     menu entry string buffer pointer
  66.     #-12    = Address of subroutine to handle submenu creation:
  67.           If 0 then it assumes the submenu pointer is valid
  68.           If >0 then it is the address of code to call to get the
  69.            leaf window or menu (see below for entry/exit conditions)
  70.           If the top bit is set then it is the address of a Zap
  71.            command to be called with R2=16. (see E-Commands)
  72.     #-8    = Index word (or command data if b31 of #-4 set)
  73.     #-4    = Address of routine to perform menu action:
  74.           If 0 then no action is taken if the entry is clicked on.
  75.           If >0 then it is the address of the interpret code to call
  76.            (see below for entry/exit conditions)
  77.           If the top bit is set then it is the address of a Zap
  78.            command to be executed when the menu entry is clicked on.
  79.  
  80. The update menu sub is called when the menu is created to update the 'ticks'
  81. etc. This is called when a menu is created/recreated. The entry/exit
  82. conditions are:
  83.  
  84.     \E    R0=offset of this menu in previous menu
  85.         R6=w_format value (opt_format if R8=0)
  86.         R7=w_flags value (opt_flags if R8=0)
  87.         R8/R9=window (or 0 if called from iconbar menu)
  88.         R10=address of the start of the wimp menu structure
  89.         R11<>your workspace
  90.     \X    You may corrupt R0-R11 VS on error etc
  91.     
  92. The interpret code is called when the menu is clicked on. Adjust clicks etc
  93. are handled automatically. Perform the menu action. The update code will be
  94. called again if the menu is recreated. The entry/exit conditions are:
  95.  
  96.     \E    R0=offset in menu (=R11!-4)
  97.         R1=index word (=R10!-8)
  98.         R2=address of menu item start
  99.         R3=address of previous menu item start
  100.         R6=w_format value (opt_format if R8=0)
  101.         R7=w_flags value (opt_flags if R8=0)
  102.         R8/R9=window (or 0 if called from iconbar menu)
  103.         R10=address of text for this menu item
  104.         R11=end of list of menu offsets as returned by the wimp
  105.     \X    You may corrupt R0-R11 VS on error etc
  106.     
  107. The menu warning code is called when the menu warning bit is set and Zap gets
  108. a menu warning message. It has entry/exit conditions:
  109.  
  110.     \E    R5=offset of this item in the (now previous) menu
  111.         R8/R9=window (or 0 if called from iconbar menu)
  112.         R10=address of text for this menu item
  113.         R11=menu warning block as returned by the wimp
  114.     \X    R1=pointer to submenu (in wimp format with values at negative
  115.         offsets as described above)
  116.         OR window handle of leaf window to be opened.
  117.         OR 0 in case of an error/not being able to create it.
  118.  
  119. All leaf windows should be warned and opened by returning R1 as the leaf
  120. window handle.
  121.  
  122. Note, after the menu has been converted to wimp format (as described above)
  123. then all submenus are warned so that the 'update menu code' is only called
  124. when that particular submenu is opened. Hence you can have menus used
  125. repeatedly at several different places in the tree with different options on
  126. each.
  127.